Skip to main content
Redhat Developers  Logo
  • Products

    Platforms

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat AI
      Red Hat AI
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • View All Red Hat Products

    Featured

    • Red Hat build of OpenJDK
    • Red Hat Developer Hub
    • Red Hat JBoss Enterprise Application Platform
    • Red Hat OpenShift Dev Spaces
    • Red Hat OpenShift Local
    • Red Hat Developer Sandbox

      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Secure Development & Architectures

      • Security
      • Secure coding
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • Product Documentation
    • API Catalog
    • Legacy Documentation
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

Application binary interface compatibility testing with libabigail

Will your binary run on another distro or another version? Find out with abidb.

May 20, 2024
Frank Eigler
Related topics:
C, C#, C++CompilersDatabasesLinux
Related products:
Red Hat Enterprise Linux

Share:

    This article explores how you can leverage application binary interface (ABI) compatibility testing with libabigail to determine the functionality of binaries running on older distributions or versions.

    Software evolution and compatibility

    Linux distributions are a living thing. During their lifetime, they are born at release, receive updates, and eventually "die" when support ends. They spawn descendant distributions. They sometimes even fight! The whole point of the distribution is to make an interdependent, cohesive whole, so there are many shared components. When those shared components are changed within a distribution, the question of compatibility is imminent.

    Application binary interface (ABI) compatibility is a specific type of dependency: between separately compiled binaries and shared libraries. If the provider or the user of any interface—function call? variable type?—is changed, will the complete system still work at run time? The answer is an easy YES if you recompile the world, but that is not practical (unless you're into Gentoo.) You end up with a new library and an old binary (or vice versa.) A well-written library will exhibit discipline: using symbol versioning for functions, limiting or eliminating visible data type changes. But, even with the necessary expertise, mistakes can happen. You will wonder: will this still run? You can test the program and hope for the best, but a successful run doesn't guarantee that every code path will mesh its new counterpart. A mismatch can cause crashes or data corruption later.

    libabigail for static ABI compatibility testing

    Instead of haphazard testing, you need tools for systematic comparison of the two sides of the linkage interface between binaries. From this need, libabigail was built in 2013. It includes tools to analyze the debugging data of each binary, to infer fine-grained ABI data on both sides of an interface: what a caller uses, and what the callee provides. Another tool compares two alternative versions of the same binary or library, to answer whether they are substitutable—whether they provide the same interface. Note that libabigail compatibility checks currently focus on function presence, and type compatibility related to the layout of complex variables in memory. These are the most common sources of incompatibility that occur with evolving software.  Other aspects of ABI compatibility are also being investigated.

    But operating that tool requires direct access to the two or more candidate binaries. This may be easy if you just compiled one of them, and it's sitting in a new build tree. Or it may be harder, if you're trying to compare two versions of a distribution package. That would mean they have the same path and they can't be installed concurrently. Actually, I lied a little. libabigail added a mode where it can make and take an XML document form instead of a binary plus debuginfo. But for that, one needs to have the XML data for the binary or library being compared. If only someone figured out how to make it easy to collect and share all that XML!

    Introducing abidb

    One way is with a new tool, abidb, which is shipped with libabigail version 2.5. It is a wrapper on the libabigail tools to make and use ABI XML documents. The "db" part of the name stands for "database", and relates to its method of archiving these ABI XML documents: in a git repository. The repository is structured so that an entire Linux distribution's shared libraries worth of XML files may be imported into a single branch. Each version of each shared library gets a unique file name (derived from the library's file path, its ELF SONAME, and its unique build-id hash). That means that different versions of the same library will be siblings in the git filesystem. Many Linux distributions can coexist in the same git repo, on different branches. Because of the genius and efficiency of git, they can all be stored together, compressed fairly efficiently.

    This first version of abidb has two modes. abidb --submit /path/to/libfoo.so generates an ABI XML document for the given file using libabigail's abidw, and deposits it into an appropriate place in the current git repository. abidb can also process entire RPM/DEB archive files, and run the "submit" operation on each shared library found inside. If debuginfo is not immediately available, the tool consults any configured debuginfo servers to fetch them automatically. You may rerun to add data for new versions installed since last time. This results in a Git branch that you may push to a central repository, or use in situ. All the usual git tools and techniques work to manage distribution, control, and garbage collection. Figure 1 depicts this mode.

    abidb submit operation
    abidb submit operation
    License under CC0 1.0.
    Figure 1: abidb submit operatoin.

    The other mode is abidb --check BINARY, as shown in Figure 2. This mode takes a given binary, identifies all the shared libraries it uses (by the outgoing DT_NEEDED SONAME references). Then, using the libabigail abidiff tool, it then compares the binary to the ABI XML of each shared library with the same SONAME from the git repo. If this reveals any ABI mismatch, then details are printed, and you will find out that some version of a shared library is not in fact compatible with the binary. Note that it's not necessary to install the shared library files at all: just get a copy of the XML git repo from somewhere. In fact, the comparison target need not be the same distribution you're running, as long as someone collected its ABI XML bits and merged them into your git repo.

    abidb check operation
    abidb check operation
    License under CC0 1.0.
    Figure 2: abidb check operation.

    We anticipate other modes coming on line soon, such as comparing shared library versions directly to each other, based on their ABI XML. This could assist distribution maintainers who need to maintain ABI compatibility guarantees, by comparing new builds to all relevant previous ones. It could be a part of build pipeline automation. This may assist certain multiplatform binary packaging efforts like AppImage.

    abidb public repo

    To accompany the abidb tool, we are prototyping a public git repo of ABI XML data for a variety of Linux distributions. We have started populating this with some of the distributions closest to our hearts, and would love to extend it with others. Simple shell scripts can take installation media or a bunch of archives, and import an entire distribution into an abidb Git repo over a few hours. If you wish to publish that content to the world, rather than using it privately, we may be able to help by merging it into our public abidb.git repo on sourceware.org. Get in touch at libabigail@sourceware.org and help crowdsource.

    Related Posts

    • Comparing ABIs for Compatibility with libabigail - Part 1

    • ABI change analysis of Fedora packages

    • How the GNU C Library handles backward compatibility

    • Debuginfo is not just for debugging programs

    • Deploying debuginfod servers for your developers

    • How to write an ABI compliance checker using Libabigail

    Recent Posts

    • What qualifies for Red Hat Developer Subscription for Teams?

    • How to run OpenAI's gpt-oss models locally with RamaLama

    • Using DNS over TLS in OpenShift to secure communications

    • Scaling DeepSeek and Sparse MoE models in vLLM with llm-d

    • Multicluster authentication with Ansible Automation Platform

    What’s up next?

    The Advanced Linux Commands cheat sheet presents a collection of Linux commands and executables for developers who are using the Linux operating system in advanced programming scenarios.

    Get the cheat sheet
    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit
    © 2025 Red Hat

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue