ELF abisum - an ABI checksumming tool for ELF binaries

Overview

ELF abisum is a tool to generate an ABI checksum of ELF binaries from their DWARF debug information. The DWARF debug information contains lots of useful bits for checking ABIs, including types of variables, members of structs, signatures of functions, etc.

ELF abisum is still in the early stage of development. It could produce wrong results.

Goal

The goal of ELF abisum is to make a build process faster by reducing unnecessary relinking of binaries. Suppose you develop a program using lots of DSOs (Dynamic Shared Objects, aka .so files) and there are dependencies to the DSOs in your Makefile like:

foobar: liba.so libb.so libc.so libd.so ...
	gcc -o foobar -L. -la -lb -lc -ld ...

In this case, every time you make a small change in a DSO, you need to relink the all DSOs to the dynamic executable foobar. The time to relink isn't negligible if the number of DSOs is big. In theory, the relinking isn't always necessary. If there are no ABI changes in a DSO, there is no need to relink the DSO to a dynamic executable that depends on the DSO.

ELF abisum is developed to solve this problem by reducing unnecessary relinking of binaries. Using abisum, the Makefile above could be rewritten as follows:

foobar: liba.abi libb.abi libc.abi libd.abi ...
	gcc -o foobar -L. -la -lb -lc -ld ...

liba.abi: liba.so
	abisum liba.so > liba.abi.tmp
	if ! cmp -s liba.abi.tmp liba.abi; then mv liba.abi.tmp liba.abi; fi

Note that to use abisum in a build process, DSOs should be built with -g option of GCC, that inserts DWARF debug information into binaries.

Non Goal

ELF abisum isn't a tool to enforce ABI stability. Abisum generates completely different checksums from two DSOs even if the new one preserves upward compatibility. See Upward Compatible Cases and Future Plans for details.

License and Availability

ELF abisum is open source software with ABSOLUTELY NO WARRANTY under the terms of the Apache License 2.0. The latest version should be available at http://abisum.sourceforge.net/

Prerequisites

ELF abisum is mostly written in C++. You need gcc, make, and all other standard development tools. Below are additional non-standard packages used by abisum.

Debian/Ubuntu package name
libdwarf libdwarf-dev
libelf libelfg0-dev
Boost libboost-dev
PCRE libpcre3-dev
openssl libssl-dev

Usage

To get a checksum of /usr/lib/libfoo.so, run the following and abisum emits the checksum to standard out.

% abisum /usr/lib/libfoo.so
382adb993e196f725b28b9163ef515ca

If no debug information is available in a binary, abisum emits a warning to standard error and falls back to file-based checksumming (exactly the same with what md5sum does).

% abisum /usr/lib/libbar.so
abisum: /usr/lib/libbar.so: no debug information
b6a6d4700a102b704ceadee90c4df232

You can specify -s option to suppress the warning message.

Test Cases

The followings are currently prepared test cases. Here, we see ABI changes from the view point of a linker. That's why we consider reordering and changing of enums aren't ABI changes. A .c or .cc file that includes .h in which enums are changed, should be recompiled anyway.

ABI Changes

ABI Non-Changes

False Positive Cases

There are several false positive cases where abisum produces different checksums even if there are no ABI changes. From the viewpoint of abisum's purpose, these cases are not a big issue, while false negative cases, where abisum produces the same checksum even if there are ABI changes, is a big problem. The false negative cases should never happen. If they happen, it's a bug. We welcome your bug reports.

Upward Compatible Cases

Since abisum only generates checksums, it cannot deal with upward compatible changes. abisum produces completely different checksums even if binaries preserve upward compatibility. See Future plans.

Implementation Note

Currently, abisum uses Doug Lea's malloc 2.8.3. It appears to be substantially faster for abisum than ptmalloc2 used in GLIBC 2.3.x.

Future Plans


Satoru Takabayashi (satorux google.com)