abicompat - Man Page

abicompat — check ABI compatibility

abicompat checks that an application that links against a given shared library is still ABI compatible with a subsequent version of that library.  If the new version of the library introduces an ABI incompatibility, then abicompat hints the user at what exactly that incompatibility is.

abicompat [options] [<application> <shared-library-first-version> <shared-library-second-version>]

The exit code of the abicompat command is either 0 if the ABI of the binaries being compared are equal, or non-zero if they differ or if the tool encountered an error.

In the later case, the exit code is a 8-bits-wide bit field in which each bit has a specific meaning.

The first bit, of value 1, named ABIDIFF_ERROR means there was an error.

The second bit, of value 2, named ABIDIFF_USAGE_ERROR means there was an error in the way the user invoked the tool.  It might be set, for instance, if the user invoked the tool with an unknown command line switch, with a wrong number or argument, etc.  If this bit is set, then the ABIDIFF_ERROR bit must be set as well.

The third bit, of value 4, named ABIDIFF_ABI_CHANGE means the ABI of the binaries being compared are different.

The fourth bit, of value 8, named ABIDIFF_ABI_INCOMPATIBLE_CHANGE means the ABI of the binaries compared are different in an incompatible way.  If this bit is set, then the ABIDIFF_ABI_CHANGE bit must be set as well.  If the ABIDIFF_ABI_CHANGE is set and the ABIDIFF_INCOMPATIBLE_CHANGE is NOT set, then it means that the ABIs being compared might or might not be compatible.  In that case, a human being needs to review the ABI changes to decide if they are compatible or not.

The remaining bits are not used for the moment.

• Detecting a possible ABI incompatibility in a new shared library version:

  $ cat -n test0.h
       1  struct foo
       2  {
       3    int m0;
       4
       5    foo()
       6      : m0()
       7    {}
       8  };
       9
      10  foo*
      11  first_func();
      12
      13  void
      14  second_func(foo&);
      15
      16  void
      17  third_func();
  $
  
  $ cat -n test-app.cc
       1  // Compile with:
       2  //  g++ -g -Wall -o test-app -L. -ltest-0 test-app.cc
       3
       4  #include "test0.h"
       5
       6  int
       7  main()
       8  {
       9    foo* f = first_func();
      10    second_func(*f);
      11    return 0;
      12  }
  $
  
  $ cat -n test0.cc
       1  // Compile this with:
       2  //  g++ -g -Wall -shared -o libtest-0.so test0.cc
       3
       4  #include "test0.h"
       5
       6  foo*
       7  first_func()
       8  {
       9    foo* f = new foo();
      10    return f;
      11  }
      12
      13  void
      14  second_func(foo&)
      15  {
      16  }
      17
      18  void
      19  third_func()
      20  {
      21  }
  $
  
  $ cat -n test1.h
       1  struct foo
       2  {
       3    int  m0;
       4    char m1; /* <-- a new member got added here! */
       5
       6    foo()
       7    : m0(),
       8      m1()
       9    {}
      10  };
      11
      12  foo*
      13  first_func();
      14
      15  void
      16  second_func(foo&);
      17
      18  void
      19  third_func();
  $
  
  $ cat -n test1.cc
       1  // Compile this with:
       2  //  g++ -g -Wall -shared -o libtest-1.so test1.cc
       3
       4  #include "test1.h"
       5
       6  foo*
       7  first_func()
       8  {
       9    foo* f = new foo();
      10    return f;
      11  }
      12
      13  void
      14  second_func(foo&)
      15  {
      16  }
      17
      18  /* Let's comment out the definition of third_func()
      19     void
      20     third_func()
      21     {
      22     }
      23  */
  $

  • Compile the first and second versions of the libraries: libtest-0.so and libtest-1.so:

    $ g++ -g -Wall -shared -o libtest-0.so test0.cc
    $ g++ -g -Wall -shared -o libtest-1.so test1.cc

  • Compile the application and link it against the first version of the library, creating the test-app binary:

    $ g++ -g -Wall -o test-app -L. -ltest-0.so test-app.cc

  • Now, use abicompat to see if libtest-1.so is ABI compatible with app, with respect to the ABI of libtest-0.so:

    $ abicompat test-app libtest-0.so libtest-1.so
    ELF file 'test-app' might not be ABI compatible with 'libtest-1.so' due to differences with 'libtest-0.so' below:
    Functions changes summary: 0 Removed, 2 Changed, 0 Added functions
    Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
    
    2 functions with some indirect sub-type change:
    
      [C]'function foo* first_func()' has some indirect sub-type changes:
        return type changed:
          in pointed to type 'struct foo':
            size changed from 32 to 64 bits
            1 data member insertion:
              'char foo::m1', at offset 32 (in bits)
      [C]'function void second_func(foo&)' has some indirect sub-type changes:
        parameter 0 of type 'foo&' has sub-type changes:
          referenced type 'struct foo' changed, as reported earlier
    
    $

  • Now use the weak mode of abicompat, that is, providing just the application and the new version of the library:

    $ abicompat --weak-mode test-app libtest-1.so
    functions defined in library
        'libtest-1.so'
    have sub-types that are different from what application
        'test-app'
    expects:
    
      function foo* first_func():
        return type changed:
          in pointed to type 'struct foo':
            size changed from 32 to 64 bits
            1 data member insertion:
              'char foo::m1', at offset 32 (in bits)
    
    $

Dodji Seketeli

2014-2024, Red Hat, Inc.