ABIPKGDIFF(1)

📦
version 3.0 · 17 versions
, in centos-stream 9

✨ NAME ✨

okay so bestie, welcome to abipkgdiff (aka ABIPKGDIFF(1), straight outta the Libabigail squad 🧚) — it compares the ABIs of ELF files inside software packages.

abipkgdiff compares the Application Binary Interfaces (ABI) of the ELF binaries contained in two sets of software packages. The software package formats currently supported are Deb, RPM, tar archives (either compressed or not) and plain directories that contain binaries.

The ABI of the binaries contained in the second set of packages is compared against the ABI of the binaries contained in the first set of packages. 💅

okay and like, for a comprehensive ABI change report that includes changes about function and variable sub-types, the two input package sets must be accompanied with their debug information packages that contain debug information either in DWARF, CTF or in BTF formats. But bestie, heads up: some packages contain binaries that embed the debug information directly in a section of said binaries. In those cases, obviously, no separate debug information package is needed as the tool will find the debug information inside the binaries. 🎀

By default, abipkgdiff uses debug information in DWARF format, if present, otherwise it compares binaries interfaces using debug information in CTF or in BTF formats, if present. Finally, if no debug info in these formats is found, it only considers ELF symbols and report about their addition or removal.

This tool uses the libabigail library to analyze the binary as well as its associated debug information. Here is its general mode of operation. 👑

When instructed to do so, a binary and its associated debug information is read and analyzed. To that effect, libabigail analyzes by default the descriptions of the types reachable by the interfaces (functions and variables) that are visible outside of their translation unit. Once that analysis is done, an Application Binary Interface Corpus is constructed by only considering the subset of types reachable from interfaces associated to ELF symbols that are defined and exported by the binary. It's that final ABI corpus which libabigail considers as representing the ABI of the analyzed binary. fr fr.

Libabigail then has capabilities to generate textual representations of ABI Corpora, compare them, analyze their changes and report about them. iconic behavior, honestly. ✨

🌸 INVOCATION 🌸

abipkgdiff [options] <package1> <package2>

package1 and package2 are the packages that contain the binaries to be compared.

An alternate invocation style would be:

abipkgdiff [options] --set1 <pkg1-v1> <pkg2-v1> <pkg3-v1> \
                     --set2 <pkg1-v2> <pkg2-v2> <pkg3-v2>

or

abipkgdiff [options] –set1 <pkg1-v1>,<pkg2-v1>,<pkg3-v1>
       –set2 <pkg1-v2>,<pkg2-v2>,<pkg3-v2>

where the ABI of binaries contained in the second set of packages are compared against binaries contained in the first set of packages. 🫶

Packages in a set are delimited either by a white spaces or by a comma.

🦋 ENVIRONMENT 🦋

abipkgdiff loads two default suppression specifications files, merges their content and use it to filter out ABI change reports that might be considered as false positives to users. no cap, it's just being nice about it.

  • 💜 Default system-wide suppression specification file
    • It's located by the optional environment variable LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE. If that environment variable is not set, then abipkgdiff tries to load the suppression file $libdir/libabigail/libabigail-default.abignore. If that file is not present, then no default system-wide suppression specification file is loaded.
  • 🍓 Default user suppression specification file.
    • It's located by the optional environment LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE. If that environment variable is not set, then abipkgdiff tries to load the suppression file $HOME/.abignore. If that file is not present, then no default user suppression specification is loaded.

In addition to those default suppression specification files, abipkgdiff will also look inside the packages being compared and if it sees a file that ends with the extension .abignore, then it will consider it as a suppression specification and it will combine it to the default suppression specification that might be already loaded. sneak peek behavior 😭

The user might as well use the --suppressions option (that is documented further below) to provide a suppression specification.

  • 🌈 Parallel processing
    • The environment variable ABIGAIL_THREAD_POOL_SIZE can be set to either an integer, or a percentage value, e.g, 10%. The integer value defines the number of threads used by Libabigail to perform parallel processing when applicable. The percentage defines the percentage of the total available cores to use by Libabigail to perform the parallel processing when applicable.
    • By default, Libabigail uses all the available cores to perform its parallel processing. multitasking queen 💅

💖 OPTIONS 💖

  • --allow-non-exported-interfaces — okay so, when looking at the debug information accompanying a binary, this tool analyzes the descriptions of the types reachable by the interfaces (functions and variables) that are visible outside of their translation unit. Once that analysis is done, an ABI corpus is constructed by only considering the subset of types reachable from interfaces associated to ELF symbols that are defined and exported by the binary. It's those final ABI Corpora that are compared by this tool.

The problem with that approach however is that analyzing all the interfaces that are visible from outside their translation unit can amount to a lot of data, especially when those binaries are applications, as opposed to shared libraries. One example of such applications is the Linux Kernel. Analyzing massive ABI Corpora like these can be extremely slow. 💀

In the presence of an "average sized" binary however one can afford having libabigail analyze all interfaces that are visible outside of their translation unit, using this option.

Note that this option is turned on by default, unless we are in the presence of the Linux Kernel. 👑
  • --btf — This is used to compare packages with BTF debug information, if present.
  • --ctf — This is used to compare packages with CTF debug information, if present.
  • --debug-info-pkg1 | --d1 path — For cases where the debug information for package1 is split out into a separate file, tells abipkgdiff where to find that separate debug information package.

Note that the debug info for package1 can have been split into several different debug info packages. In that case, several instances of this options can be provided, along with those several different debug info packages. 🎀

  • --debug-info-pkg2 | --d2 path — For cases where the debug information for package2 is split out into a separate file, tells abipkgdiff where to find that separate debug information package.

Note that the debug info for package2 can have been split into several different debug info packages. In that case, several instances of this options can be provided, along with those several different debug info packages. 🎀

  • --devel-pkg1 | --devel1 path — Specifies where to find the Development Package associated with the first package to be compared. That Development Package at path should at least contain header files in which public types exposed by the libraries (of the first package to be compared) are defined. When this option is provided, the tool filters out reports about ABI changes to types that are NOT defined in these header files.
  • --devel-pkg2 | --devel2 path — Specifies where to find the Development Package associated with the second package to be compared. That Development Package at path should at least contains header files in which public types exposed by the libraries (of the second package to be compared) are defined. When this option is provided, the tool filters out reports about ABI changes to types that are NOT defined in these header files.
  • --drop-private-types — This option is to be used with the --devel-pkg1 and --devel-pkg2 options. With this option, types that are NOT defined in the headers are entirely dropped from the internal representation build by Libabigail to represent the ABI. They thus don't have to be filtered out from the final ABI change report because they are not even present in Libabigail's representation. ✨

Without this option however, those private types are kept in the internal representation and later filtered out from the report.

This options thus potentially makes Libabigail consume less memory. It's meant to be mainly used to optimize the memory consumption of the tool on binaries with a lot of publicly defined and exported types.

  • --dso-only — Compare ELF files that are shared libraries, only. Do not compare executable files, for instance.
  • --exported-interfaces-only — By default, when looking at the debug information accompanying a binary, this tool analyzes the descriptions of the types reachable by the interfaces (functions and variables) that are visible outside of their translation unit. Once that analysis is done, an ABI corpus is constructed by only considering the subset of types reachable from interfaces associated to ELF symbols that are defined and exported by the binary. It's those final ABI Corpora that are compared by this tool.

The problem with that approach however is that analyzing all the interfaces that are visible from outside their translation unit can amount to a lot of data, especially when those binaries are applications, as opposed to shared libraries. One example of such applications is the Linux Kernel. Analyzing massive ABI corpora like these can be extremely slow. 😭

To mitigate that performance issue, this option allows libabigail to only analyze types that are reachable from interfaces associated with defined and exported ELF symbols.

Note that this option is turned on by default when analyzing the Linux Kernel. Otherwise, it's turned off by default.
  • --fail-no-dbg — Make the program fail and return a non-zero exit code if couldn't read any of the debug information that comes from the debug info packages that were given on the command line. If no debug info package were provided on the command line then this option is not active.
Heads up bestie 💖 — that last option hands back a non-zero exit code, and the constant it returns is ABIDIFF_ERROR. Wanna know the actual number? The exit code docs have you covered, iykyk.
  • --full-impact, -f — when you're diffing two Linux Kernel packages, this tells abipkgdiff to spit out the so-called full impact report, which is literally the default report kind that abidiff gives you. It looks like this:
$ abidiff libtest-v0.so libtest-v1.so
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

1 function with some indirect sub-type change:

  [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
    parameter 1 of type 'C&' has sub-type changes:
      in referenced type 'struct C' at test-v1.cc:7:1:
        type size hasn't changed
        1 data member change:
         type of 'leaf* C::m0' changed:
           in pointed to type 'struct leaf' at test-v1.cc:1:1:
             type size changed from 32 to 64 bits
             1 data member insertion:
               'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1

$
  • --harmless — in the diff report, show only the harmless changes. Normally those get filtered out of the report to keep the clutter down and give you a way better chance of spotting the real ABI issues. 🌸
  • --help | -h — shows a short help blurb about the command and dips. ✨
  • --ignore-soname — okay so picture this: two binaries with different SONAMEs but the same name in the old and new packages. This option forces abipkgdiff to compare them anyway, regardless of that very obvious SONAME glow-up. Why would you? So you can analyse the ABI changes that might have led devs to change the SONAME in the first place. 🕵️‍♀️
  • --impacted-interfaces — when it's showing leaf changes, this tells abipkgdiff to show the list of impacted interfaces. So use it in addition to the --leaf-changes-only option, or when you're comparing two Linux Kernel packages. Otherwise? It's simply ignored, bestie, it does nothing. 💀
  • --keep-tmp-files — don't erase the temporary directory files that get created while the tool runs. Keep the mess, king. 🎀
  • --leaf-changes-only, -l — only show leaf changes, so no impact analysis report. This option implies --redundant.

The typical output of abipkgdiff and abidiff when comparing two binaries — the thing we're calling the full impact report — looks like this:

$ abidiff libtest-v0.so libtest-v1.so
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

1 function with some indirect sub-type change:

  [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
    parameter 1 of type 'C&' has sub-type changes:
      in referenced type 'struct C' at test-v1.cc:7:1:
        type size hasn't changed
        1 data member change:
         type of 'leaf* C::m0' changed:
           in pointed to type 'struct leaf' at test-v1.cc:1:1:
             type size changed from 32 to 64 bits
             1 data member insertion:
               'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1

$

So in that example the report is telling you how the data member insertion change of "struct leaf" is reachable from the function "void fn(C&)". In other words, it doesn't just show you the data member change on "struct leaf" — it also shows you the impact of that change on the function "void fn(C&)". Iconic behaviour, honestly. 👑

In abidiff (and abipkgdiff) parlance, the change on "struct leaf" is called a leaf change. So the --leaf-changes-only + --impacted-interfaces options show, well, only the leaf change. And it goes like this:

$ abidiff -l libtest-v0.so libtest-v1.so
'struct leaf' changed:
  type size changed from 32 to 64 bits
  1 data member insertion:
    'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1

  one impacted interface:
    function void fn(C&)
$

See how the report wraps up by showing the list of interfaces impacted by the leaf change? That's the effect of the extra --impacted-interfaces option. ✨

And if you do not want that list of impacted interfaces? Just don't use the --impacted-interface option. You can read all about that option below anyway, no stress. 🫶

Please note: when you're comparing two Linux Kernel packages, this leaf changes report is what gets emitted, by default. The normal so-called full impact report can be emitted with the --full-impact option, which is documented further down. 💅

  • --linux-kernel-abi-whitelist | -w <path-to-whitelist> — when comparing two Linux kernel RPM packages, this option points at the white list of names of ELF symbols of functions and variables that must be compared for ABI changes. That white list is called a "Linux kernel ABI white list".

Any other function or variable whose ELF symbol isn't in that white list? Not considered by the ABI comparison process at all. Bye. 👋

If this option isn't provided — so, no white list — then the ABI of all publicly defined and exported functions and global variables by the Linux Kernel binaries gets compared.

Also note: if a white list package is given as a parameter, this option handles it just fine, like if the --wp option was used. 🎀

  • --no-abignore — don't search the package for the presence of suppression files.
  • --no-added-binaries — don't show the list of binaries that got added to the second package.

Please note that the presence of those added binaries is not considered an ABI change by this tool, so it has zero impact on the tool's exit code. It's purely informational. Removed binaries, though? Those are considered an ABI change. 💀

  • --no-added-syms — don't show the list of functions, variables, or literally any symbol that was added.
  • --no-assume-odr-for-cplusplus — when analysing a binary coming from C++ code using DWARF debug information, libabigail assumes the One Definition Rule to speed up the analysis. In that case, when several types have the same name in the binary, they're all assumed to be equal.

This option disables that assumption and tells libabigail to actually actually compare the types to figure out if they're equal. ✨

  • --no-default-suppression — don't load the default suppression specification files.
  • --no-leverage-dwarf-factorization — when analysing a binary whose DWARF debug information was processed with the DWZ tool, the type information is supposed to already be factorized. libabigail uses that context to do some speed optimizations.

This option disables those optimizations. 🐢

  • --no-linkage-name — in the resulting report, don't display the linkage names of the added, removed, or changed functions or variables.
  • --no-parallel — by default, abipkgdiff uses every processor it has available to run stuff concurrently. This option tells it not to extract packages or run comparisons in parallel. One lane only, bestie. 🚗
  • --non-reachable-types, -t — analyse and emit change reports for all the types in the binary, including the ones that aren't reachable from global functions and variables.
Fair warning: this can cause some serious performance degradation, because the number of types analyzed can be huge. 😭 But if you pair it with the --devel-pkg{1,2} options, the extra non-reachable types analyzed get restricted to those defined in the public header files carried by the referenced development packages, which hopefully makes the performance hit acceptable.

Also, using this option alongside suppression specifications (by also using the --suppressions option) might help keep the number of analyzed types — and the potential performance degradation — under control. 🧚

Note that without this option, only types reachable from global functions and variables are analyzed, so the tool only detects and reports changes on those reachable types.

  • --no-show-locs — don't show information about where in the second shared library the respective type was changed.
  • --no-show-relative-offset-changes — without this option, when a data member's offset changes, the change report doesn't just mention the older and newer offset, it also mentions by how many bits the data member changed. With this option, that last bit isn't shown. 🎀
  • --no-unreferenced-symbols — in the resulting report, don't display change information about function and variable symbols that aren't referenced by any debug information. Note that for these not-referenced-by-debug-info symbols, the change information displayed is either added or removed symbols.
  • --show-bits — show sizes and offsets in bits, not bytes. This option is activated by default. ⭐
  • --show-bytes — show sizes and offsets in bytes, not bits. By default, sizes and offsets are shown in bits.
  • --show-dec — show sizes and offsets in decimal base. This option is activated by default. 🔢
  • --show-hex — show sizes and offsets in hexadecimal base. 🔥
  • --show-identical-binaries — show the names of all the binaries compared, including the ones whose ABI compares equal. By default, when this option isn't provided, only binaries with ABI changes get mentioned in the output. 👀
  • --private-dso — by default, abipkgdiff does not compare DSOs that are private to the RPM package. A private DSO is a DSO whose SONAME is NOT advertised in the "provides" property of the RPM.

This option tells abipkgdiff to also compare DSOs that are NOT advertised in the "provides" property of the RPM. 💅

Okay so real talk before we keep scrolling: the fact that abipkgdiff skips private DSOs by default is lowkey a feature that only exists for RPMs right now. Like, only RPMs have it. If you're on some other package format and you're like "bestie where's my private-DSO skipping" — the page literally says patches adding that feature for other package formats would be happily accepted. 👀 So if that's your hyperfixation, go off.

  • --redundant — Shows redundant changes in the diff reports. A redundant change is one that's already been shown somewhere else in the same report — so yeah, turning this on means you're getting the double-texting of diff output. You asked for it, bestie. ✨
  • --self-check — This one's a lil' internal vibe check for the underlying Libabigail library. When you use it, the command expects only one input package, plus the debug info packages that go with it. Then it compares every binary inside the package against its own ABIXML representation. If Libabigail is behaving, the comparison should come back with the empty set — literally nothing. 👑 If it doesn't, that means there's an issue that ought to be fixed. This is the tool for the Libabigail devs doing regression testing, fr fr. Here's what using it looks like:
$ abipkgdiff --self-check --d1 mesa-libGLU-debuginfo-9.0.1-3.fc33.x86_64.rpm  mesa-libGLU-9.0.1-3.fc33.x86_64.rpm
 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
$
  • --set1 <package1-path> <package2-path> <package2-path> … — Sets up the first set of packages, the ones whose binaries get compared against the second set. Heads up though: you specify that second set with the --set2 option. 💅
  • --set2 <package1-path> <package2-path> <package2-path> … — Sets up the second set of packages, whose binaries are compared against the second one. And yep, you guessed it — the first set is what you specify with the --set1 option. They're a matched set, your honor. 🫶
  • --suppressions | --suppr <path-to-suppressions> — Points at a suppression specification file living at path-to-suppressions. And no cap: this option can show up multiple times on the command line, and if it does, all of those suppression specification files get taken into account. 🌸
Also important: by default, if you don't pass this option at all, the default suppression specification files get loaded. So it's never truly suppression-less, iykyk. 😭
  • --version | -v — Shows the version of the program, then exits. Iconic, brief, does exactly what it says. ⭐
  • --wp <path-to-whitelist-package> — For when you're comparing two Linux kernel RPM packages: this points at an RPM package that contains several white lists of names of ELF symbols of functions and variables that must be compared for ABI changes. Those white lists are literally called "Linux kernel ABI white lists". 🎀

So from that white list package's content, the program picks the appropriate Linux kernel ABI white list to use when comparing the ABI of the Linux kernel binaries inside the kernel packages you gave on the command line. That chosen white list contains the names of ELF symbols of functions and variables that must be compared for ABI changes. Anything whose ELF symbol isn't in that white list just doesn't get considered by the ABI comparison at all. Filtered. Gone. Not on the guest list. 💀

You can pass this option twice — but not more than twice — giving one white list package for each Linux Kernel package on the command line. If you don't pass it, so there's no white list, then the ABI of all publicly defined and exported functions and global variables by the Linux Kernel binaries gets compared. 🌈

  • --thread-pool-size <N|N%> | -j <N|N%> — Sets the size of the thread pool Libabigail uses for parallel processing. The size is either a number of threads, or a percentage of the total number of available cores on the machine. By default? All the available cores on the machine get used for the parallel processing. She multithreads, your honor. 🔥

Also: the environment variable ABIGAIL_THREAD_POOL_SIZE can be set to similar values. But if this command line option is present, it supersedes the value of the environment variable. Periodt. 👑

  • --verbose — Emits verbose progress messages. For when you simply must know what's happening at all times. 🙈
  • --verbose-diff — Emits timed verbose progress messages about the diffing process. Also, this option implies the --verbose one, so you get the regular verbose vibes too. ⏱️✨

🌈 RETURN VALUE 🌈

The exit code of abipkgdiff is 0 if the ABI of the binaries you compared are equal. If they differ, or if the tool hit an error — non-zero. Simple as that.

In that latter case, the value of the exit code is the same as it is for the abidiff tool. So if you know abidiff, you already know. iykyk. 💅

👑 AUTHOR 👑

Dodji Seketeli

2014-2026, Red Hat, Inc.

And that's the whole page, bestie — you made it to the end! 🫶 This lil' gem is the abipkgdiff(1) manual, dated Oct 08, 2026, and it is, as always, brought to you by the fine folks at Red Hat, Inc. Go diff some packages, slay, and remember: skip those private DSOs responsibly. 💖✨🦋

📦 where this page comes from