Some compiler options, macros, version upgrades can break binary compatibility. Documentation should warn about this.

Submitted by Zsbán Ambrus

Assigned to Nobody

Link to original bugzilla bug (#1349)
Version: 3.3 (current stable)

Description

The ABI of Eigen can differ depending on the version of Eigen, certain compiler options and certain Eigen-specific macros the user is allowed to define. The documentation warns about some of these in "http://eigen.tuxfamily.org/dox/TopicPreprocessorDirectives.html", but not all. The documentation should be improved to make it more clear what exactly changes the ABI and what doesn't.

One particularly important aspect is alignment. On x86_64 (and x86_32 too), Eigen sometimes decides that some data has to be aligned to 32 bytes, when it was previously aligned to only 16 bytes. Alignment to 32 is active if you use Eigen version 3.3 or later (not the 3.2 branch) and tell the compiler to compile with AVX instructions. This can change both the representation (size) of fixed size matrix types, but can also change what allocating functions are used for dynamic matrix types. This means that if you compile a library that references Eigen types in its interface, then change compiler options to use AVX or upgrade to Eigen 3.3, then compile the rest of your program that way without recompiling the library, you could get mysterious silent memory corruptions in the worst case. The case of enabling AVX instructions is particularly problematic, because people often use a higher instruction set for their programs than what the precompiled libraries installed on their system use. (Relevant gcc options include -march=*, -mavx, -mavx2) Enabling AVX2 instruction sets might also affect alignment, I don't know if it does.

Certain Eigen-specific macros the user can define also affect the ABI: these include EIGEN_DONT_ALIGN, EIGEN_DONT_ALIGN_STATICALLY, EIGEN_MALLOC_ALREADY_ALIGNED, EIGEN_MAX_STATIC_ALIGN_BYTES, EIGEN_MAX_ALIGN_BYTES, EIGEN_DEFAULT_DENSE_INDEX_TYPE, EIGEN_DEFAULT_TO_ROW_MAJOR.

The documentation should warn about surprising ABI break situations, especially ones that could cause silent memory corruption or other misbehaviour (as opposed to merely crashes or link errors). It should try to make it clear, as much as possible, which compiler options, version differences and macros can affect binary compatibility. (For the compiler options, it's enough to mention those options that do not normally change binary compatibility of typical libraries.) Yes, this is difficult.