Compatible Builds

What are binary compatible builds?

OpenOffice.org is truly a huge software project. One of the most annoying aspects of huge software projects is a long build time.

There are many ways to reduce long build times and we tried some of them (parallel builds, the include guard optimization, pre-compiled headers, ccache) but churning ten million or so (give or take a million) through the compiler will always take some time. But the absolute majority of changes do not require extensive rebuilds and so many OpenOffice.org developers opt for a partial build.

The usual way to implement partial builds is to define full dependencies between the different parts of a project. Executing a top level "make" will then rebuild all the required parts. It's possible to work this way with OpenOffice.org, full dependencies are enabled by default.

But just creating and checking the dependency files take so much time that developers are using workarounds. A popular one is to disable dependencies on a full build (and reenable dependencies later). Another one is to work with partial dependencies.

Partial dependencies means that during the build process only the dependencies inside an OpenOffice.org module are checked, but dependencies to other modules are ignored. Leaving out the dependencies to other modules greatly reduces the number of checks and speeds up the build significantly, but of course, comes with a price. Developers now must consider the effect a change will have on other modules. This has always been true for source code incompatible changes (like renaming a method inside a class) but now binary compatibility (like adding a data member to a class) is an issue, too. The build system will not enforce a rebuild of object files outside the module if only partial dependencies are enabled. The developer is responsible for recognizing the situation and to rebuild the affected modules, or even the whole tree upwards from the changed module.

CWS entries in EIS have now a field which developers can use to indicate a module which has been changed binary incompatible. If several modules are changed binary incompatible the lowest module in the build hierarchy needs to be entered. Please make good use of this field because it eases the live of release engineering and co-developers.

Claiming that a change in one module does not affect object files in other modules is essentially claiming that the change is source code level and binary compatible and thus we call builds with only partial dependencies and without removing old object files "compatible builds". A gross hack, true, but one which can save a lot of time.

There are other reasons to stay binary compatible than just shorter build times. Some OpenOffice.org distributions feature patch updates, patches can be much smaller if the different OpenOffice.org parts are binary compatible to each other. Commercial third party components also require certain binary compatibility guarantees.

What changes are binary incompatible?

Now, what changes are "binary incompatible"? If you just change *.cxx files in your modules this is certainly not binary incompatible. If you change headers which are internal to a module and they do not export stuff directly or indirectly to "solver" (meaning to other modules), it's still a compatible change.

Binary incompatible changes in exported headers include:

• adding a data member to a class/struct
• changing the size of a data member
• reordering data members
• adding a new virtual method to a class/struct
• renaming of a class method or "standalone" function
• changing the signature of a method
• adding a new default parameter to a method
• changing the base class(es) of a class

Notable non-trivial binary compatible changes are:

• adding a non-virtual method to a class
• adding a whole new class to a header
• adding new "standalone" functions

If in doubt please flag a CWS as incompatible.