hdf5/.github/workflows/abi-report.yml

name: hdf5 Check Application Binary Interface (ABI)

# Triggers the workflow on a call from another workflow
on:
  workflow_call:
    inputs:
      use_tag:
        description: 'Release version tag'
        type: string
        required: false
        default: snapshot
      use_environ:
        description: 'Environment to locate files'
        type: string
        required: true
        default: snapshots
      file_base:
        description: "The common base name of the binary"
        required: true
        type: string
      file_ref:
        description: "The reference release tag to compare against. Leave empty to auto-detect the latest published HDFGroup/hdf5 release."
        required: false
        type: string
        default: ''

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-24.04
    continue-on-error: true

    steps:
      - name: Install System dependencies
        run: |
          sudo apt update
          sudo apt install -q -y abi-compliance-checker abi-dumper
          sudo apt install -q -y japi-compliance-checker

      - name: Resolve reference release tag
        id: resolve-file-ref
        run: |
          if [[ -n "${{ inputs.file_ref }}" ]]; then
            REF="${{ inputs.file_ref }}"
          else
            REF=$(curl -fsSL https://api.github.com/repos/HDFGroup/hdf5/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')
            if [[ -z "$REF" ]]; then
              echo "::error::Could not auto-detect the latest HDFGroup/hdf5 release tag"
              exit 1
            fi
          fi
          echo "Using reference release: $REF"
          echo "FILE_REF=$REF" >> $GITHUB_OUTPUT

      - name: Convert hdf5 reference name (Linux)
        id: convert-hdf5lib-refname
        run:  |
          FILE_DOTS=$(echo "${{ steps.resolve-file-ref.outputs.FILE_REF }}" | sed -r "s/([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+).*/\1\.\2\.\3-\4/")
          echo "HDF5R_DOTS=$FILE_DOTS" >> $GITHUB_OUTPUT
          FILE_DOTSMAIN=$(echo "${{ steps.resolve-file-ref.outputs.FILE_REF }}" | sed -r "s/([0-9]+)\.([0-9]+)\.([0-9]+).*/\1\.\2\.\3/")
          echo "HDF5R_DOTSMAIN=$FILE_DOTSMAIN" >> $GITHUB_OUTPUT

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Get published binary (Linux)
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
            name: tgz-ubuntu-2404_gcc-binary
            path: ${{ github.workspace }}

      - name: List files for the space (Linux)
        run: |
          ls -l ${{ github.workspace }}

      - name: Uncompress gh binary (Linux)
        run: tar -zxvf ${{ github.workspace }}/${{ inputs.file_base }}-ubuntu-2404_gcc.tar.gz

      - name: Uncompress hdf5 binary (Linux)
        run:  |
          cd "${{ github.workspace }}/hdf5"
          tar -zxvf ${{ github.workspace }}/hdf5/HDF5-*-Linux.tar.gz --strip-components 1

      - name: List files for the HDF space (Linux)
        run: |
          ls -l ${{ github.workspace }}/hdf5
          ls -l ${{ github.workspace }}/hdf5/HDF_Group/HDF5

      - name: set hdf5lib name
        id: set-hdf5lib-name
        run: |
          HDF5DIR=${{ github.workspace }}/hdf5/HDF_Group/HDF5/
          FILE_NAME_HDF5=$(ls ${{ github.workspace }}/hdf5/HDF_Group/HDF5)
          FILE_VERS=$(echo "$FILE_NAME_HDF5" | sed -r "s/([0-9]+\.[0-9]+\.[0-9]+).*/\1/")
          echo "HDF5_ROOT=$HDF5DIR$FILE_NAME_HDF5" >> $GITHUB_OUTPUT
          echo "HDF5_VERS=$FILE_VERS" >> $GITHUB_OUTPUT

      - name: Download reference version
        run: |
          mkdir "${{ github.workspace }}/hdf5R"
          cd "${{ github.workspace }}/hdf5R"
          wget -q https://github.com/HDFGroup/hdf5/releases/download/${{ steps.resolve-file-ref.outputs.FILE_REF }}/hdf5-${{ steps.convert-hdf5lib-refname.outputs.HDF5R_DOTS }}-ubuntu-2404_gcc.tar.gz
          tar zxf hdf5-${{ steps.convert-hdf5lib-refname.outputs.HDF5R_DOTS }}-ubuntu-2404_gcc.tar.gz

      - name: List files for the space (Linux)
        run: |
          ls -l ${{ github.workspace }}/hdf5R

      - name: Uncompress hdf5 reference binary (Linux)
        run:  |
          cd "${{ github.workspace }}/hdf5R"
          tar -zxvf ${{ github.workspace }}/hdf5R/hdf5/HDF5-${{ steps.resolve-file-ref.outputs.FILE_REF }}-Linux.tar.gz --strip-components 1

      - name: List files for the HDFR space (Linux)
        run: |
          ls -l ${{ github.workspace }}/hdf5R
          ls -l ${{ github.workspace }}/hdf5R/HDF_Group/HDF5

      - name: set hdf5lib reference name
        id: set-hdf5lib-refname
        run: |
          HDF5RDIR=${{ github.workspace }}/hdf5R/HDF_Group/HDF5/
          FILE_NAME_HDF5R=$(ls ${{ github.workspace }}/hdf5R/HDF_Group/HDF5)
          echo "HDF5R_ROOT=$HDF5RDIR$FILE_NAME_HDF5R" >> $GITHUB_OUTPUT
          echo "HDF5R_VERS=$FILE_NAME_HDF5R" >> $GITHUB_OUTPUT

      - name: List files for the lib spaces (Linux)
        run: |
          ls -l ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/lib
          ls -l ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/lib

      - name: Run Java API report
        run: |
          japi-compliance-checker ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/lib/jarhdf5-${{ steps.convert-hdf5lib-refname.outputs.HDF5R_DOTSMAIN }}.jar ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/lib/jarhdf5-${{ steps.set-hdf5lib-name.outputs.HDF5_VERS }}.jar
        continue-on-error: true

      - name: Run ABI report
        run: |
          abi-dumper ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/lib/libhdf5.so -o ABI-0.dump -public-headers ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/include
          abi-dumper ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/lib/libhdf5.so -o ABI-1.dump -public-headers ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/include
          abi-compliance-checker -l ${{ inputs.file_base }} -old ABI-0.dump -new ABI-1.dump
        continue-on-error: true

      - name: Run hl ABI report
        run: |
          abi-dumper ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/lib/libhdf5_hl.so -o ABI-2.dump -public-headers ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/include
          abi-dumper ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/lib/libhdf5_hl.so -o ABI-3.dump -public-headers ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/include
          abi-compliance-checker -l ${{ inputs.file_base }}_hl -old ABI-2.dump -new ABI-3.dump
        continue-on-error: true

      - name: Run cpp ABI report
        run: |
          abi-dumper ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/lib/libhdf5_cpp.so -o ABI-4.dump -public-headers ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/include
          abi-dumper ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/lib/libhdf5_cpp.so -o ABI-5.dump -public-headers ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/include
          abi-compliance-checker -l ${{ inputs.file_base }}_cpp -old ABI-4.dump -new ABI-5.dump
        continue-on-error: true

      - name: Run hl_cpp ABI report
        run: |
          abi-dumper ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/lib/libhdf5_hl_cpp.so -o ABI-6.dump -public-headers ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/include
          abi-dumper ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/lib/libhdf5_hl_cpp.so -o ABI-7.dump -public-headers ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/include
          abi-compliance-checker -l ${{ inputs.file_base }}_hl_cpp -old ABI-6.dump -new ABI-7.dump
        continue-on-error: true

      # NOTE ON READING THE FORTRAN REPORT: expect a large number of "Low" severity
      # "Problems with Symbols" findings on the generic KIND/RANK-generated buffer
      # procedures in H5_gen.F90 (h5aread_*, h5awrite_*, h5dread_*, h5dwrite_*), e.g.
      # "Type of Nth parameter buf has been changed from integer(kind=K)[X] to
      # integer(kind=K)[Y]". These are false positives: abi-dumper misreads gfortran's
      # DWARF encoding of assumed-shape array descriptors as if the bound were a fixed
      # compile-time array size, so the reported X/Y values are debug-info noise, not a
      # real interface change. Real signal shows up in Added/Removed Symbols and in
      # Medium/High severity findings (e.g. a module-level data size actually changing) -
      # focus review there and disregard bulk Low-severity Symbol findings from H5_gen.F90.
      - name: Run fortran ABI report
        run: |
          abi-dumper ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/lib/libhdf5_fortran.so -o ABI-8.dump
          abi-dumper ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/lib/libhdf5_fortran.so -o ABI-9.dump
          abi-compliance-checker -l ${{ inputs.file_base }}_fortran -old ABI-8.dump -new ABI-9.dump
        continue-on-error: true

      - name: Run fortran exported symbol diff
        run: |
          # gfortran mangled names don't encode argument lists, so abi-compliance-checker
          # (DWARF-based) is the primary signal above; this is a cheap supplementary check
          # that still catches added/removed exported symbols even if debug info is stripped.
          nm -D --defined-only ${{ steps.set-hdf5lib-refname.outputs.HDF5R_ROOT }}/lib/libhdf5_fortran.so | awk '{print $3}' | sort > old_fortran_syms.txt
          nm -D --defined-only ${{ steps.set-hdf5lib-name.outputs.HDF5_ROOT }}/lib/libhdf5_fortran.so | awk '{print $3}' | sort > new_fortran_syms.txt
          diff -u old_fortran_syms.txt new_fortran_syms.txt > ${{ inputs.file_base }}-hdf5_fortran_symbol_diff.txt || true
          echo "=== Fortran exported symbol diff (reference vs new) ==="
          cat ${{ inputs.file_base }}-hdf5_fortran_symbol_diff.txt
        continue-on-error: true

      - name: Copy ABI reports
        run: |
          cp compat_reports/jarhdf5-/${{ steps.convert-hdf5lib-refname.outputs.HDF5R_DOTSMAIN }}_to_${{ steps.set-hdf5lib-name.outputs.HDF5_VERS }}/compat_report.html ${{ inputs.file_base }}-java_compat_report.html
          ls -l compat_reports/${{ inputs.file_base }}/X_to_Y
          cp compat_reports/${{ inputs.file_base }}/X_to_Y/compat_report.html ${{ inputs.file_base }}-hdf5_compat_report.html
          ls -l compat_reports/${{ inputs.file_base }}_hl/X_to_Y
          cp compat_reports/${{ inputs.file_base }}_hl/X_to_Y/compat_report.html ${{ inputs.file_base }}-hdf5_hl_compat_report.html
          ls -l compat_reports/${{ inputs.file_base }}_cpp/X_to_Y
          cp compat_reports/${{ inputs.file_base }}_cpp/X_to_Y/compat_report.html ${{ inputs.file_base }}-hdf5_cpp_compat_report.html
          ls -l compat_reports/${{ inputs.file_base }}_hl_cpp/X_to_Y
          cp compat_reports/${{ inputs.file_base }}_hl_cpp/X_to_Y/compat_report.html ${{ inputs.file_base }}-hdf5_hl_cpp_compat_report.html
          ls -l compat_reports/${{ inputs.file_base }}_fortran/X_to_Y
          cp compat_reports/${{ inputs.file_base }}_fortran/X_to_Y/compat_report.html ${{ inputs.file_base }}-hdf5_fortran_compat_report.html
        continue-on-error: true

      - name: List files for the report spaces (Linux)
        run: |
          ls -l compat_reports
          ls -l *.html

      - name: Publish ABI reports
        id: publish-abi-reports
        run: |
          mkdir "${{ runner.workspace }}/buildabi"
          mkdir "${{ runner.workspace }}/buildabi/hdf5"
          cp ${{ inputs.file_base }}-hdf5_compat_report.html ${{ runner.workspace }}/buildabi/hdf5
          cp ${{ inputs.file_base }}-hdf5_hl_compat_report.html ${{ runner.workspace }}/buildabi/hdf5
          cp ${{ inputs.file_base }}-hdf5_cpp_compat_report.html ${{ runner.workspace }}/buildabi/hdf5
          cp ${{ inputs.file_base }}-hdf5_fortran_compat_report.html ${{ runner.workspace }}/buildabi/hdf5
          cp ${{ inputs.file_base }}-hdf5_fortran_symbol_diff.txt ${{ runner.workspace }}/buildabi/hdf5
          cp ${{ inputs.file_base }}-java_compat_report.html ${{ runner.workspace }}/buildabi/hdf5
          cd "${{ runner.workspace }}/buildabi"
          tar -zcvf ${{ inputs.file_base }}.html.abi.reports.tar.gz hdf5
        shell: bash

      - name: Save output as artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v5
        with:
          name: abi-reports
          path: |
            ${{ runner.workspace }}/buildabi/${{ inputs.file_base }}.html.abi.reports.tar.gz