Introduction
Libabigail based tools emit reports about ABI artifacts (types, functions, variables, symbols, etc ...) that have changed. Some users might want some reports about some changed artifacts to be suppressed. This is where the filtering capabilities of Libabigail can be helpful.
Suppression specifications
Users tell Libabigail (and its tools) what ABI artifact change report to suppress by providing a file which contains suppression directives. That file is called a suppression specification. The exact syntax of that file is define in the Libabigail documentation
Let's focus on the case of the abipkgdiff tool which aims at comparing the ABIs of binaries embedded in RPMs.
There are three ways to provide suppression specifications to Libabigail through abipkgdiff:
Add a .abignore file to the RPMs
If the RPM package contains a file which name ends with the extension .abignore then the tool considers it as a suppression specification.
The rpminspect tool runs abidiff when comparing package builds and it will look in both the source and binary RPM packages for .abignore files. Some packages just add the .abignore file to the SRPM with a Source directive in the spec file so it is included in the SRPM.
Pass suppression specifications to abipkgdiff using command a command line option
As explained in the documentation of abipkgdiff, using --suppressions suppr-spec.abignore option will make the tool consider the suppr-spec.abignore file as a suppression specification.
Define default suppression specifications
Libabigail allows users to define default suppression specifications. If the file ~/.abignore is present, it's considered by all Libabigail tools as a "default user suppression specification". That specification will apply to all the Libabigail tool invocations made the current user.
Note that by default, there is also a system-wide default suppression specification that is installed at $libdir/libabigail/libabigail-default.abignore that is applied to all Libabigail tools invocations on the system.
suppression specification examples
An example of suppression specification file to provide to the Libabigail system to avoid comparing some dynamic shared object (aka DSO) binaries would typically carry this content:
[suppress_file] # Just keep DSOs that have a version number, i.e, which file name end-up with a version number. # All other DSOs will be discarded and their changes won't be reported file_name_not_regexp=.*\\.so\\.[0-9]+
Here is a little context for the suppression specification above.
Usually, DSOs that are meant to be consumed by the user of a given project by way of linking them against their application are versioned. That is, each one of them have a version number. And that version number can be seen at the end of the file's extension. Each new release of the DSO thus has a different version number.
On the other hand, DSO that don't have a version number, tend to be meant to be consumed by the project itself. That is, some internal code of the project will need that non-versioned DSO.
Of course these are just mere conventions. And they might not apply to some projects. But then when they do apply, it might be a good idea to avoid comparing non-versioned DSOs because their ABI changes are not problematic, those DSOs are meant for private consumption only. In that case you can use the suppression specification above.
Note also that when several suppression specification files are provided to the Libabigail system, the suppression directives coming from the different files are combined.