tools: Add a g-ir-diff tool
Submitted by Philip Withnall
Here’s a series of patches to add a new g-ir-diff tool. This is intended to be used to verify that there are no API breaks between one version of a GIR file and the next, for some definition of ‘API break’ which is decided by the library author.
While tools exist for checking the stability of a C API between releases (such as the ABI Compliance Checker (http://ispras.linuxbase.org/index.php/ABI_compliance_checker), no such tool exists for GIR APIs. The best I've seen is a
diff -u of the two GIR files, which is subject to a lot of false positives, and requires the developer to manually determine whether each change is an API break.
The ultimate goal is for this to be integrated into the release process for any library which installs a stable GIR file, giving a reliable (in the sense that it is allowed to cause
make distcheck to fail) indication that a project has broken its introspected API. However, more tooling is needed before that can be a reality — build system integration and a solid set of guidelines for recommended ways of storing old versions of GIR files, for example.
One thing which should be considered before the interface for this tool is finalised is how it would be best to fit it into CI systems and
make check. I think any approach has to have an archive of historical GIR files to compare against — the question is how to best store this.
The idea I'm toying with at the moment is to store it in the version control system (i.e. git; I don't care about anything else). If there were some way of extracting the GIR files from each tagged release, it would be easy to compare the current ones in the build tree against those from the most recent release.
In the easiest case, the GIR files are stored in git directly (for example, if they are hand-written). In most projects, they are generated (by g-ir-scanner). In this case, I suggest using
git notes to add the generated GIR files to each release tag in a special notes namespace. They could then be retrieved as trivially as in the easiest case.
Of course, this would mean that g-ir-diff needs to be able to read input files from stdin or somesuch other magic, which it doesn’t currently do.
The attached patches are basically complete as a first draft. More documentation and unit tests could be added, and there are a few minor TODO comments. I’m attaching the patches here to get feedback on the overall concept, and the suggested command line interface. Once I have some feedback, I can polish up the patches ready for actual review.