Specify library version as part of the headers

[wjakob]

Dear @Tessil,

would you consider specifying the robin-map version as part of the header files?

I am the author of nanobind, a Python <-> C++ binding layer that uses robin-map in various internal data structures. Robin-map has been great, I am really happy with both design and performance.

nanobind pins a specific version of robin-map to ensure ABI compatibility. That way, multiple separately compiled C++ extensions can pool their internal data structures to exchange information about types and objects.

But one issue now that nanobind is being used by more people and different distributions is that they really don't like having a pinned dependency. They want to use the latest one available on the OS or package manager. That introduces the possibility of ABI contract violations.

Having an easily queriable #define as part of the robin map headers would make it easier to catch such future changes (perhaps unlikely, as this seems like a relatively stable project, but one can never be sure)

[Tessil]

Hi @wjakob

Thank you for your contribution, I'm glad the library is useful to nanobind.

The PR looks like a good addition. Just one minor comment, I would prefer to use the TSL_RH_ prefix instead of just TSL_ to avoid any potential conflict with other libraries in the tsl space (I might also add the version info in them).

[wjakob]

Certainly, let's use whatever prefix you like. I will amend the commit. Since creating the PR, I realized that simply adding version numbers isn't the whole story. For them to be useful, the digits need to have an assigned meaning, and that should probably also be part of this.

In SemVer, the patch release part of the version number indicates minor bugfixes. Minor number increments communicate added features, and major number increments communicate API breaks.

Since this is a C++ data structure, there are two separate concerns: ABI breaks and API breaks. For simplicity, my suggestion would be to combine those two and have the following convention:

// A change of the major version indicates an API and/or ABI break (change of in-memory layout of the data structure)
#define TSL_RH_VERSION_MAJOR 1
// A change of the minor version indicates the addition of a feature without impact on the API/ABI
#define TSL_RH_VERSION_MINOR 2
// A change of the patch version indicates a bugfix without additional functionality
#define TSL_RH_VERSION_PATCH 2

For example, this way, I could static_assert on TSL_RH_VERSION_MAJOR in my project, and that will prevent compilation of libraries with an incompatible ABI.

Can you let me know if this sounds good to you?

[Tessil]

Yes, this sounds reasonable.

The library is mainly in maintenance mode (bug fix & others) as I consider it features complete in general, so I don't expect any big change in the future and if I do, I would create a 2.0 version.

[wjakob]

Great — I amended the commit.

[Tessil]

Thanks, I merged the change and will check to create a new 1.2.2 release (updating the different versions values).

[wjakob]

Thank you!

[Tessil]

Released: https://github.com/Tessil/robin-map/releases/tag/v1.2.2