Tracking C++ lib public API changes

Question

I'm currently working on large C++ Qt based project which is a about to go under a major re-factor of its public API and it would be nice to have a tool that can generate a report on which methods have been added or removed from build to build.

I know there is a tool for Java to do this and I think there might be one for .NET but I couldn't, after a bit of searching, find anything for C++.

Does one exist. Cross platform would be nice, or if only in Linux that would be fine too.

Answer 1

If you use Doxygen or some similar tool to document your API then you can diff the table-of-contents.

• This is something you should be doing anyway.
  • (You can also tell Doxygen to find undocumented functions.)
• You can apply it easily to ancient checkins without changing anything.
• The Doxygen and its ilk know enough about the language to be sensitive to private and public.
• This solution can be applied to many languages and is not dependent on a particular IDE.
• No third-party software is required (given that you already have a documentation generator).

Answer 2

Check the bottom of the commercial list for apidiff, I think it'll be the closest match.

The suggestion of using 'nm' isn't a bad one, you can run

nm <binary_or_lib> | c++filt

And it'll generate a decent snapshot, that will need a fair amount of post-processing.

There's lots of ways to roll your own on this one:

1. Doxygen can generate an XML file that has all the class / member / method information that you could then mine for building class trees. It would then be a matter of comparing trees. Some useful post-processing scripts / utilities can be found @ http://www.doxygen.nl/helpers.html

2. If you're compiling with gcc, egypt is a novel approach that uses the intermediate RTL to produce call-dependency graphs - it seems like it wouldn't be that difficult to use a similar method to generate basic API information.

3. GCC-XMLwill generate an XML representations of compiled code, a bit more low level than Doxygen as it provides a mechanism for writing wrapper code.

4. cppHeaderParser, a python module will generate nice python object representations of headers giving an easy way to generate the API maps.

5. ctags generates a tag database which could probably be processed. It has problems with C++ namespaces though.

Some commercial solutions

1. scitool's Understand does a great job of mapping software out and has a perl API for querying its database.

2. MagicDraw is kind of a heavy-weight tool centered around UML, but it can reverse-engineer an existing C++ code-base and generate meta-information.

3. apidiff seems to be a pretty affordable tool and given the criteria (cross-platform, C++) is likely the closest match.

Answer 3

Instead of allowing all the visible symbols to export from your library automatically, you can use an explicit list of exported symbols. For larger libraries this is even recommended.

In Windows you use a .DEF file to export symbols from a DLL.

In Unix-likes you use a linker script to do it.