Versioning pre-built indexes

# Versioning of pre-built indexes

In CDT 4.0.1 support for versioning of pre-built indexes was added. This means that if you release pre-built indexes for the same content (for example, the same SDK version), but they were built with different versions of CDT, then a suitable version will now be used automatically. The previous behaviour assumed only one format version of any particular content would be provided via the CIndex extension point.

It is important to distinguish between two versions: the content version and the index format version. A content version refers to the version of the source code being indexed independent of how it is represented in the index e.g. SDK v1.0 and SDK v1.2. The index format version is the version of the internal representation of the index. This document is about coping with the latter.

Our versioning policy for index formats is that they should be compatible within major (yearly) release versions. That is if you build an index using CDT 4.0.X it should work with CDT 4.0.Y. This policy should mean that ISVs do not need to worry about index format versioning, but this page describes how to handle it should it be necessary (for example bugzilla 189811).Each pre-built index carries a string ID which identifies it uniquely within a logical index - i.e. it identifies the content (e.g MySDK v1.2). When multiple pre-built indexes are provided with the same ID, the particular one for use is disambiguated automatically by CDT which chooses the most recent compatible version.

## Compatibility Table

This table shows the compatibility of pre-built indexes built with one version of CDT and used with another. “Built With” is the vertical axis.

Built With \ Use With | CDT 4.0 | CDT 4.0.1 | CDT Next** |
CDT 4.0 | Yes* | Yes* | No |
CDT 4.0.1 | Yes* | Yes | No |
CDT Next** | No | No | Yes |

Note that even though in the PDOM format has its own internal versioning scheme, consumers of official CDT releases need only be aware of compatibility constraints between these releases.

* with performance issues in very large projects. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=189811

** represents the next major release of CDT. It is assumed significant changes to the PDOM database will occur.

## Example scenario

The figure above shows an example scenario where pre-built indexes are contributed by multiple plug-ins. The same content is contributed in multiple index format versions. The versions selected for use by each version of CDT are highlighted in gray.

Versioning Bugzilla: https://bugs.eclipse.org/bugs/show_bug.cgi?id=196338