How does _ITERATOR_DEBUG_LEVEL change STL container layouts?
Changing _ITERATOR_DEBUG_LEVEL directly affects the internal layout and binary representation of STL containers such as std::vector, std::string, etc., in MSVC. When debug iterator support is enabled (usually with _ITERATOR_DEBUG_LEVEL = 2), additional members, debug checks, and bookkeeping structures are added to STL containers to monitor iterator validity and container boundaries. These extra fields and mechanisms alter the size and memory layout of these types compared to release builds where _ITERATOR_DEBUG_LEVEL = 0, which omits these debug helpers.
How Layout Changes
- Debug mode containers have extra data for iterator tracking, which increases their size and changes their alignment and structure compared to release containers.
- This structural difference means that passing containers or iterators between modules compiled with different _ITERATOR_DEBUG_LEVEL values leads to incompatibility and possible crashes, since the binary layout expected is not the same.
- For example, std::string and std::vector will have different sizeof values and memory arrangement depending on the value of _ITERATOR_DEBUG_LEVEL, causing interoperability issues across DLL boundaries or mixed build configurations.
Why It Matters
These changes make debug builds more robust against invalid iterator usage but prevent reliable interoperation with release builds or code compiled with a different debug level. It’s strongly advised not to share STL objects across build boundaries unless build settings (including _ITERATOR_DEBUG_LEVEL) match exactly on both sides.
In summary, _ITERATOR_DEBUG_LEVEL modifies STL container layouts by adding extra members and debug infrastructure for iterator checking, making their representation incompatible between debug and release builds in MSVC.
How does this affect add-on developers?
If you use STL in your Windows add-ons, set _ITERATOR_DEBUG_LEVEL to 0, as you can see in the CMakeLists.txt files accompanying the example add-ons, or as in SetGlobalCompilerDefinitions in https://github.com/GRAPHISOFT/archicad-addon-cmake-tools/blob/main/CMakeCommon.cmake, and link to ACAP_STAT.lib even in debug builds.
