17.6. Debugging Interface Issues

Although most Abuild.interface files are reasonably simple and have easily understandable consequences, there will inevitably be situations in which some interface variable has a value that you don't understand. For example, you might see an assignment in one Abuild.interface file that appears to have no effect, or you may wonder which of a very long list of dependencies was responsible for a particular variable assignment or declaration.

Starting with abuild version 1.0.3, you can have abuild dump everything it knows about a build item's interface variables into an XML file. Do this by passing the --dump-interfaces flag to any abuild command that builds something. Doing so will cause abuild to create interface dump files for every build item including those that don't build anything and even those that have no Abuild.interface files themselves.

For build items that do not have build files, abuild creates a file called .ab-interface-dump.xml in the output directory for every platform on which that build item exists. This file contains information about all interface variables that are known to that item. For build items that have build files, abuild creates two files: .ab-interface-dump.before-build.xml and .ab-interface-dump.after-build.xml. If a build has no Abuild.interface or the item's Abuild.interface has no after-build files, the two files are identical and are analogous to .ab-interface-dump.xml files of build items that don't have build files. Otherwise, the .ab-interface-dump.before-build.xml file reflects the interface as seen by the build item itself (before any after-build files are loaded), and the .ab-interface-dump.after-build.xml shows what interface this build item provides to items that depend on it.

Note that the interface dump files contain not just a list of variables with their values but a complete list of everything abuild knows about each variable. This includes its type, where it was declared, every assignment that was made to it, every reset of every variable, etc. When you reference an interface variable, abuild computes the value on the fly, sometimes influenced by interface flags that may be in effect. To get maximum benefit from the information in the interface dump files, you must understand how this works. For those details, please refer to Section 33.7, “Implementation of the Abuild Interface System”. The format of the interface dump file is described in Appendix G, --dump-interfaces Format.